Zum Inhalt

Server Setup Guide für adaptor:ex

Dieses Tutorial hilft dir, wenn du adaptor:ex als Webservice nutzen möchtest der 24/7 läuft und von überall, wo es eine Stabile Internetverbindung gibt, erreicht werden kann.

Wir erstellen ein Setup das auf jedem geläufigen linux Server funktionieren sollte. Auch wenn du ein abweichendes Setup hast, das aber noch Probleme bereitet, könntest du hier fündig werden.

Ziel ist es den adaptor:ex editor als auch alle web fähigen APIs über das Netz auf deiner eigenen Domain erreichbar zu machen und mit Nutzer Authentifizierung und let's encrypt Zertifikaten zu sichern.

Was du benötigst

Web server

Du brauchst einen eigenen (virtuellen) Webserver den du per SSH bedienen kannst.

Das Betriebssystem des Servers sollte eine geläufige Linux Distribution sein (z.B. Ubuntu oder Debian). Die meisten Anweisungen in diesem Tutorial sollten aber auch auf anderen Betriebssystemen anwendbar sein.

Subdomains

Du benötigst einen Domain Namen für den du Subdomains erstellen und die du auf die IP deines Servers verweisen kannst.

Wie du neue subdomains für deinen Domainnamen anlegen kannst hängt von deinem Domain provider ab.

Wir benötigen für den adaptor:ex Server und den adaptor:ex client jeweils eine Subdomain.

Du kannst für einen von beiden (ich empfehle für den client) natürlich auch den Haupt Domain Namen verwenden, wenn du noch keine Webseite oder einen Webservice damit bedienst

Im folgenden Beispiel ist überall dort, wo du deine eigene Domain angeben musst für den adaptor:ex Server adaptor-server.myurl.org und für den adaptor:ex client adaptor.myurl.org angegeben.

Wenn du zwei Domain Namen eingerichtet hast, verweise sie jeweils auf die IP deines Servers. Du kannst die IP auf einem Linux Server mit dem Befehl ifconfig herausfinden.

Die IP auf die wir die Domains verweisen findest du in der mit ifconfig angezeigten Liste für gewöhnlich unter eth0.

Passe für deine Domainnamen den A-Record Eintrag an indem du in beiden Fällen die IPv4 IP deines Servers dort angibst

Den Server einrichten

Docker

Installiere Docker auf deinem Server. Wenn du einen Server mit Ubuntu Instaalation nutzt, folge den Anweisungen auf dieser Seite: https://docs.docker.com/engine/install/ubuntu/

Docker Compose

Wir werden eine Docker Compose Datei verwenden um adaptor:ex und alle nötigen anderen Services einzurichten. Dazu erweitern wir die adaptor:ex docker-compose.yml Datei.

Erstelle eine neue Datei docker-compose.yml indem du den text editor nano aufrufst:

nano docker-compose.yml

Füge die folgenden Docker Compose Anweisungen ein:

version: '3'

services:
  mongodb:
    image: mongo:bionic
    expose:
      - 27017
    restart: always
    command: [ "--bind_ip_all", "--replSet", "adaptor-repl" ]
    volumes:
      - mongo_db_data:/data/db
    # See also: https://www.upsync.dev/2021/02/02/run-mongo-replica-set.html
    healthcheck:
      test: test $$(echo "rs.initiate({_id:'adaptor-repl',members:[{_id:0,host:\"mongodb:27017\"}]}).ok || rs.status().ok" | mongo --port 27017 --quiet) -eq 1
      interval: 10s
      start_period: 30s
    networks:
      - mongonetwork

  adaptor_server:
    image: registry.gitlab.com/machina_ex/adaptor_ex/adaptor_ex_server
    # build: adaptor_ex_server/ # use this to build local git tree
    restart: always
    depends_on:
      - mongodb
    tty: true
    stdin_open: true
    #entrypoint: [ "node", "index.js", "--headless"] # use this if you don't need mongodb
    entrypoint: [ "node", "index.js", "--headless", "-d", "mongodb", "-m","mongodb://mongodb:27017/?replicaSet=adaptor-repl", "--url", "https://adaptor-server.myurl.org", "--auth", "basic" ]
    volumes:
      - ./adaptor_data:/usr/src/app/data
    environment:
      - VIRTUAL_HOST=adaptor-server.myurl.org
      - LETSENCRYPT_HOST=adaptor-server.myurl.org
      - LETSENCRYPT_EMAIL=your@email.de
      - VIRTUAL_PORT=8080
    networks:
      - proxy-tier
      - mongonetwork

  adaptor_client:
    image: registry.gitlab.com/machina_ex/adaptor_ex/adaptor_ex_client
    # build: adaptor_ex_client/ # use this to build local git tree
    restart: always
    volumes:
      - ./adaptor_client_config.json:/public/config.json
    environment:
      - VIRTUAL_HOST=adaptor.myurl.org
      - LETSENCRYPT_HOST=adaptor.myurl.org
      - LETSENCRYPT_EMAIL=your@email.de
    networks:
      - proxy-tier
  proxy:
    build: proxy/
    restart: always
    ports:
      - 80:80
      - 443:443
    labels:
      com.github.jrcs.letsencrypt_nginx_proxy_companion.nginx_proxy: "true"
    volumes:
      - certs:/etc/nginx/certs:ro
      - vhost.d:/etc/nginx/vhost.d
      - html:/usr/share/nginx/html
      - /var/run/docker.sock:/tmp/docker.sock:ro
    networks:
      - proxy-tier

  letsencrypt-companion:
    image: jrcs/letsencrypt-nginx-proxy-companion
    restart: always
    volumes:
      - certs:/etc/nginx/certs
      - vhost.d:/etc/nginx/vhost.d
      - html:/usr/share/nginx/html
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - proxy-tier
    depends_on:
      - proxy

volumes:
  certs:
  vhost.d:
  html:
  mongo_db_data:

networks:
  proxy-tier:
  mongonetwork:

Du musst ein paar Änderungen an der Docker Compose Datei vornehmen damit sie auf deinen Server angepasst ist.

  1. Ersetze adaptor-server.myurl.org durch deine eigene (sub-) Domain die du für den Server vorgesehen hast an 3 Stellen unter adaptor_server:
    entrypoint: [ "node", "index.js", "--headless", "-d", "mongodb", "-m","mongodb://mongodb:27017/?replicaSet=adaptor-repl", "--url", "https://adaptor-server.myurl.org" ]
    volumes:
      - ./adaptor_data:/usr/src/app/data
    environment:
      - VIRTUAL_HOST=adaptor-server.myurl.org
      - LETSENCRYPT_HOST=adaptor-server.myurl.org
  1. Ersetze adaptor.myurl.org durch deine eigene (sub-) Domain die du für den adaptor:ex client vorgesehen hast an 2 Stellen unter adaptor_client:
    environment:
      - VIRTUAL_HOST=adaptor.myurl.org
      - LETSENCRYPT_HOST=adaptor.myurl.org
  1. Ersetze die E-mail Adresse your@email.de die für die Erstellung des let's encrypt Zertifikates verwendet werden soll jeweils (also an 2 Stellen) unter adaptor_server und adaptor_client:
      - LETSENCRYPT_EMAIL=your@email.de

Client Config

Damit der adaptor:ex client die server API ausfindig machen kann erstelle die config JSON Datei, die vom client docker container aus gelesen wird:

nano adaptor_client_config.json

und füge die folgende Konfiguration ein:

{
  "API_URL": "https://adaptor-server.myurl.org/api",
  "LOG_STORE": false,
  "APP_TITLE": "adaptor:ex",
  "LOG_LEVEL": "debug",
  "COMMENT": "LOG_LEVEL is not yet implemented"
}

Bevor du die Datei speicherst, ersetze adaptor-server.myurl.org mit der adaptor server subdomain die du auch schon im Docker Compose file angegeben hast.

Proxy Dockerfile

Für den Proxy Docker Container, der das verteilen eingehender Requests auf die anderen Container übernimmt, musst du noch die folgende Docker Datei anlegen.

Erstelle einen Ordner mit dem Namen proxy:

mkdir proxy

und anschließend das Dockerfile für den proxy Container:

nano proxy/Dockerfile

Füge diesen Inhalt ein:

FROM jwilder/nginx-proxy:alpine

COPY uploadsize.conf /etc/nginx/conf.d/uploadsize.conf

Zudem müssen wir noch die Datei uploadsize.conf erstellen:

nano proxy/uploadsize.conf

und mit folgendem Inhalt füllen:

client_max_body_size 100M;
proxy_request_buffering off;

Das Setup Starten

Führe deine docker-compose.yml Datei mit dem pull Befehl aus um alle angegebenen Docker Container herunterzuladen:

docker-compose.yml pull

Ggf. musst du sudo voranstellen um den Befehl mit root Nutzer Rechten auszuführen.

Jetzt kannst du die Docker Komposition mit up -d an den Start bringen:

docker-compose.yml up -d

Server Config

Füge der adaptor:ex Server Konfiguration Nutzer hinzu mit denen du auf den Passwort geschützten Editor zugreifen kannst.

Wenn der Docker Compose Start geklappt hat findest du einen neuen Ordner adaptor_data indem sich auch die config.json Konfigurationsdatei des Servers befindet.

Öffne die Datei:

nano adaptor_data/config.json

und füge einen users Eintrag am Ende aber vor dem letzten } hinzu:

"users": [
    {
      "login": "ada",
      "password": "secure!?&"
    },
    {
      "login": "grace",
      "password": "secure123"
    }
  ]

Die Datei sollte anschließend in etwa so aussehen:

{
  "host": "http://localhost",
  "port": 8081,
  "data": "./data",
  "database": {
    "type": "mongodb",
    "url": "mongodb://mongodb:27017/?replicaSet=adaptor-repl"
  },
  "level": "debug",
  "authentication": "basic",
  "headless": true,
  "url": "https://adaptor-server.myurl.org",
  "users": [
    {
      "login": "ada",
      "password": "secure!?&"
    },
    {
      "login": "grace",
      "password": "secure123"
    }
  ]
}

Mehr Config Optionen für den adaptor:ex Server findest du unter: https://gitlab.com/machina_ex/adaptor_ex/adaptor_ex_server#configuration

Starte den adaptor:ex Server Docker Container anschließend neu um die Änderungen zu übernehmen:

docker restart machinacompose-adaptor_server-1

Ggf. weicht der Name deines adaptor:ex Server Docker Containers ab. Überprüfe die Namen deiner Docker Container mit dem Befehl:

docker ps

Das Setup überwachen

Wenn alles geklappt hat solltest du den adaptor:ex editor unter deiner Domain, die du für den client eingerichtet hast erreichen können.

Logge dich mit den Userdaten die du oben angegeben hast ein und erstelle ein neues Game um zu überprüfen ob Server und Datenbank zu erreichen sind.

Hier ein paar Befehle die für das Debugging und die Wartung deines Setup von Nutzen sein können.

Docker Container auflisten

Um zu überprüfen welche Docker Container gerade laufen nutze den Befehl:

docker ps

Hier siehst du auch unter welchem Namen du mit den Containern interagieren kannst.

Docker Container neu starten

Starte einen Docker Container neu mit restart

docker restart name_of_docker_container

Docker Container Konsole öffnen

Öffne die Console innerhalb eines Docker Containers (z.B. deinem adaptor:ex Server) mit attach

docker attach name_of_docker_container

Docker Container Log Datei anzeigen

Zeige mit logs die Log Datei eines Docker Containers an

docker logs name_of_docker_container

IP der Mongodatenbank anzeigen

Zeige mit inspect die IP unter der die MongoDB Datenbank per ssh Tunnel erreichbar ist mit folgendem Befehl an:

docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' machinacompose_mongodb-1

Passe auch hier den Namen des Containers ggf. an.